---
title: 手動安裝 Astro
description: 如何手動用 NPM、PNPM 或 Yarn 來安裝 Astro。
i18nReady: true
---
import Button from '~/components/Button.astro'
import { FileTree } from '@astrojs/starlight/components'
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

本指南將逐步帶你手動安裝並設定新的 Astro 專案。

:::tip[偏好更快的安裝方法嗎？]
改用 [create astro CLI 嚮導](/zh-tw/install/auto/)。
:::

#### 事前準備

- **Node.js** - `v18.14.1` 或更高版本。
- **文字編輯器** - 我們推薦使用 [VS Code](https://code.visualstudio.com/) 以及我們的 [官方 Astro 延伸模組](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode).
- **終端機** - Astro 可藉由命令列（CLI）來使用。

#### 安裝

如果你偏好不使用我們自動化的 `create astro` CLI 工具，你可以自己跟著下列指南來設定你的專案。

## 1. 建立你的目錄

建立一個空目錄並為你的專案命名，接著進到該目錄底下。

```bash
mkdir my-astro-project
cd my-astro-project
```
當你進到你的新目錄後，建立你專案的 `package.json` 檔。這將會用來管理你專案的依賴模組包括 Astro。如果你不熟悉這個檔案的格式，可執行下列的指令來建立一個。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm init --yes
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm init 
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn init --yes
  ```
  </Fragment>
</PackageManagerTabs>

## 2. 安裝 Astro

首先，安裝 Astro 專案的依賴模組到你的專案內。

:::note[重要]
Astro 必須安裝在本地，而不是全域。請**不要**執行 `npm install -g astro`、`pnpm add -g astro` 或 `yarn add global astro`。
:::

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro
  ```
  </Fragment>
</PackageManagerTabs>

然後在你的 `package.json` 檔案內，將 "scripts" 的內容取代如下：

```json title="package.json" del={2} ins={3-6}
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```

在這份指南中，你等等將會使用這些腳本來啟動 Astro 以及執行其他不同的指令。

## 3. 建立你的第一個頁面

在你的文字編輯器中，建立一個新檔案 `src/pages/index.astro` 到你的目錄中。這將會是你專案的第一個 Astro 頁面。

接著，複製並貼上以下的程式片段（包括 `---` 三個破折號）到上述新增的檔案中：

```astro title="src/pages/index.astro"
---
// 歡迎使用 Astro！用三個破折號圍起來的區域是「元件 frontmatter」。
// 這區的程式碼不會被瀏覽器執行。
console.log('這會在終端機執行，不是瀏覽器！');
---
<!-- 以下是「元件模板」。它是有魔法的 HTML，能幫你打造絕佳的模板。 -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>
```

## 4. 建立你的第一個靜態資源

當然你也會想建立一個 `public/` 目錄來儲存你的靜態資源。Astro 必會將這些資源帶到你最後的成品當中，所以你可以在你的元件範本（component templates）裡安心地引用這些資源。

在你的文字編輯器中，建立一個新檔案 `public/robots.txt` 到你的目錄中。`robots.txt` 是一個簡單檔案，大多數的網站會將其用來告訴像 Google 的搜尋機器人如何處理你的網站。

接著，複製並貼上以下的程式片段到上述的新增的檔案中：


```diff title="public/robots.txt"
# 範例：允許所有機器人掃描並將你的網站編入索引。
# 完整語法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```

## 5. 建立 `astro.config.mjs`

Astro 利用 `astro.config.mjs` 這個檔案來配置設定。如果你不需要設定 Astro 那此檔案並非必須，但你可能會希望現在就建立好它。

在你專案的根目錄下建立 `astro.config.mjs`，接著複製下列程式碼到該檔案中：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```

如果你想要引入像是 React, Svelte 等 [UI framework components](/zh-tw/guides/framework-components/) 或使用其它工具像是 Tailwind 或 Partytown 到你的專案中，在這裡你可以[手動引入並配置整合](/zh-tw/guides/integrations-guide/)。

<ReadMore>進一步了解 Astro 的 [API 設定參考](/zh-tw/reference/configuration-reference/)。</ReadMore>

## 6. 新增 TypeScript

透過 `tsconfig.json` 設定 TypeScript。就算你不寫 TypeScript，這個檔案也很重要。它讓像 Astro 和 VS Code 這些工具知道如何理解你的專案。缺乏 `tsconfig.json` 的話，有些功能便無法完整支援（像 npm 套件匯入）。

如果你想要寫 TypeScript，建議使用 Astro 的 `strict` 或 `strictest` 模板。所有樣板設定的詳細比較可以參考 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/)。

在專案的根目錄下建立 `tsconfig.json`，接著複製下列程式碼到該檔案中（設定 TypeScript 模板時，你可以使用 `base`、`strict` 或 `strictest`）：

```json title="tsconfig.json" "base"
{
  "extends": "astro/tsconfigs/base"
}
```
最後，新增 `src/env.d.ts`，讓 TypeScript 知道 Astro 專案裡可用的 ambient type：

```ts title="src/env.d.ts"
/// <reference types="astro/client" />
```

<ReadMore>進一步了解 Astro 的 [TypeScript 設定指南](/zh-tw/guides/typescript/#setup)。</ReadMore>

## 7. 接下來

如果你有跟著上述步驟，那你的專案應該看起來像這樣：

<FileTree>
- node_modules/
- public/
  - robots.txt
- src/
  - pages/
    - index.astro
  - env.d.ts
- astro.config.mjs
- package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等。
- package.json
- tsconfig.json
</FileTree>

恭喜！你現在已經設定好 Astro 了！

如果你完整跟著這份指南，你可以直接跳到[開始著手 Astro](/zh-tw/install/auto/#2-啟動-astro-) 來繼續並學習如何第一次啟動 Astro。
